Repository navigation
feat(portal): load custom scripts from portal.scripts - #477
sohail2721 wants to merge 41 commits into
Conversation
Each entry is { src }, an https address. The loader inserts them after
the vendor tags, in list order and not async, under the same hold on an
OAuth answer. The key a start runs once by covers the list, so a config
save under portal serve reloads with exactly the new one.
An inserted tag is now found by its src attribute as written: a selector
built from a customer's address misses on a backslash, and the script
would be inserted again on every page view.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A src that does not start with http: or https: names a file under static/. It is checked on disk with the brand's files, written to the identity file as its portal path, and inserted under the base path when the portal is hosted under one. A src that is neither an https address nor a file in static/ gets one report naming both choices, since a path that is no file is often an address without its https://. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…alytics A listed script takes a category: necessary, functional, analytics or marketing, and analytics when it names none. Under --no-analytics only necessary and functional scripts reach the portal, for a build, a preview and each config save alike. PortalConfig.withoutVendors() is withoutAnalytics() now that it drops more than the vendors, and the flag's help and the README say what it leaves out. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…pimatic
window.apimatic.analytics.subscribe(callback) hands a script every
event reported so far and then each new one, as a frozen
{ name, params, time, version: 1 }, and returns the function that
stops delivery. The feed is the page's, so a subscriber outlives the
second Analytics instance a config save under portal serve makes.
Earlier events arrive just after subscribe() returns, never inside
it, so a script can call the function it got back on the first event.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers scripts, with src as an https address or a file in static/ and the four categories. The address pattern pluginUrl had is one definition both settings use. The schema test holds the schema and the parser to the same verdict on each scripts case, and the schema's categories to the parser's list. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now lists an address and a file from static/. The built files have to hold both in a browser script, ship the file where its address points, carry the feed scripts subscribe to, and name neither script in a prerendered page. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nter The script set a property on window, which the whole-tree lint that runs after the tests refuses in a file with no browser environment. The test only checks that the file ships, so it now holds a comment and nothing else. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed itself sat there. A script could publish events or empty the history, subscribe threw when taken off the object and called on its own, and an object a page had put at that name first made every report throw. Scripts now get a frozen object holding a bound subscribe, put in place whatever was there before, and the feed is held at window.portalEventFeed, where the reporter publishes to it. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The conventions leave a class with public methods and private static helpers, and deliver() was a private instance method. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() listed every script in the head again for each tag and listed script it wanted, on every page view. It now reads them once into a set, which still keeps an address listed twice to one element. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
publish() copied the set before handing an event over, in case a callback subscribed or unsubscribed meanwhile. The set's own iteration already reaches one added in the same pass and skips one removed, and deliver() checks a subscriber is still there, so the copy did nothing. Two tests pin both cases. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…trings in their boxes (#478) Takes fumadocs-openapi from 12.6.0 to 12.6.5. That release fixes points 3 to 6 of apimatic/apimatic-io#2350, which we reported upstream as fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. With it, the playground's sign-in moves to the hand-over Fumadocs added in 12.6.2, which keeps the provider's answer out of page addresses. **12.6.5 is one day old, younger than the seven days `minimumReleaseAge` asks for.** It is merged early by decision: see "Merged before the seven days". ## What a portal gets - **A long field path in the playground stays in its panel** (points 4 and 5). The middle crumbs truncate, and Unset / Remove stay in reach. - **A long unbroken string wraps inside its box** (points 3 and 6): in a property card, a security scheme's card, and the field info popover. - **From 12.6.3, credentials are masked.** API keys and tokens are typed into password inputs, and the cURL sample shows a credential as `********`. - **From 12.6.3, the playground's rows look different.** An optional field outside the request is a muted row that one click adds; a field's name opens its description. - **From 12.6.4, the playground and the cURL sample build some requests correctly:** path parameter values are percent-encoded, form bodies keep `0`, `false` and empty fields, and cookie parameters are sent as the specification says. - **A sign-in's answer stays out of page addresses.** After a playground sign-in the reader lands back on the endpoint page at its own address; the provider's code or token no longer passes through it. The Google tags therefore load there at once, and a page opened through a link of its own ending in `?state=…` loads them too, where it used to wait for the next page. ## What changes here - `package.json`: `fumadocs-openapi` 12.6.5, and `lucide-react` 1.71.0, the lowest version 12.6.5 accepts, so there is still one copy of it. - `pnpm-lock.yaml`: five packages change (the two above, `@scalar/openapi-upgrader` 0.4.8, `@scalar/openapi-types` 0.9.9, and a new `@scalar/helpers` 0.17.1). - `pnpm-workspace.yaml`: `@scalar/json-magic` is held at 0.16.1 under `fumadocs-openapi`. 12.6.5 asks for 0.19, whose floor is Node 22.19, above the CLI's 22.14, so CI's `--engine-strict` install would refuse it. This is the same hold `chokidar` and `undici` already have. - `usage-tabs.tsx`: one comment, which said the cURL sample shows typed credentials. The sign-in hand-over, in its own commit: - `oauth-callback.ts`, `oauth.callback.tsx`: the callback page leaves its address, the provider's answer in it, in the tab's session storage, where the playground reads it since 12.6.2, and sends the reader back to the page that started the flow at that page's own address. Until now it sent them back with the answer still in the query or the `#` part. - `vendor-tags.ts`, `analytics.ts`, `playground.tsx`: the tags no longer wait for an answer to leave the address. `insertTags()` holds back on the callback page alone, and `holdsOAuthAnswer()` and `Analytics.loadTags()` are gone. - `oauth-callback.test.ts`: a new test runs Fumadocs' own handler script beside ours and holds both to the same entry in the session and the same page, so a move of that entry upstream fails the test and not a portal. Apart from that, the template compiles and behaves as before against 12.6.5. ## Merged before the seven days `fumadocs-openapi@12.6.5` turns seven days old on 23 Nov 2026 at 11:58 UTC. #472 waited for that day. This PR does not: the decision is to take the fix now. What that costs until 23 Nov: - **A full re-resolution fails.** `pnpm dedupe` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION` for `fumadocs-openapi@12.6.5`. A run that needs one adds `fumadocs-openapi@12.6.5` to `minimumReleaseAgeExclude` for that run only. - **Nothing else changes.** CI installs from the frozen lockfile, which never resolves, and `pnpm install` and `pnpm add` work as before. What speaks for the release: - It was published by Fumadocs' GitHub Actions with npm provenance, as 12.6.0 was, and it runs no install scripts. - The fix itself is one commit that changes class names in five files, fuma-nama/fumadocs@2419e7c. - The whole package was not compared with 12.6.0, and the step also takes in 12.6.1 to 12.6.4, which are three to five days old. - The other four new packages turn seven days old on 17 Nov, by 14:46 UTC. After 23 Nov, `pnpm dedupe --check` should pass without any exception. That is a check only: nothing in the lockfile needs to change. The lockfile here was resolved with a temporary `minimumReleaseAgeExclude` of five exact versions, which is not in this PR. ## A risk to know about Because of the `@scalar/json-magic` hold, the tests in this repository run json-magic 0.16.1, while an `npm install -g` of the CLI gets 0.19.1. The CLI loads this package (Fumadocs reads a specification through its magic proxy), and 0.19 rewrote that proxy. The portal tests workflow installs the packed CLI as npm does, so it covers the 0.19 side, but it runs on a push to `dev`, so only after this merges, and on Node 24. I checked that side by hand before then (below): on Node 24, and on Node 22.14.0, the CLI's floor, which is below the 22.19 that json-magic 0.19 declares. ## Checked - `test/e2e/portal-build.test.ts`: 78 passing, with the template's type-check against 12.6.5 among them. - `test/e2e/portal-serve.test.ts`: 6 passing. - The portal template's unit tests and the portal type tests: 550 passing. - No package in the lockfile is refused on Node 22.14.0 under `--engine-strict`. - I did not run the whole suite locally. In headless Chrome, on portals built from this branch with a neutral spec: | Problem | 12.6.0 | 12.6.5, as built | | --- | --- | --- | | Form under the request panel, three levels deep, 827 px wide | panel 425 px in a 400 px column | 400 px, middle crumbs truncate | | Unset hidden, five levels deep, 1142 px wide | panel 656 px in a 574 px column, Unset cannot be clicked | 574 px, Unset can be clicked | | Long inline code in a parameter's description | 7 px past the card's edge | inside the card | | Long string in the field info popover | 322 px of text in a 262 px box | no overflow | - **A playground sign-in, start to finish**, against a stand-in OAuth provider, through the hand-over: - The authorization code flow, with PKCE, and the implicit flow both sign in, and a request goes out with each one's token. - The reader returns from `/oauth/callback` to the endpoint page at its own address, the tags load there at once, and the entry the callback left in the session is gone once the playground has read it. - The refused case shows the provider's error on the callback page. - The callback page loads no tag and reports nothing, with an answer nobody started as well. A link from it loads the tags on the next page. - A page opened with `?state=CA` loads its tags at once and is reported without the parameter. - **The build a user gets**: the packed CLI installed with npm resolves 12.6.5 with json-magic 0.19.1, undici 8 and chokidar 6. It builds the same portal, and the four measurements above are the same. The tests above ran again after the hand-over commit. The four measurements, the npm-installed build and the Node 22.14.0 checks below ran before it; that commit changes the sign-in's browser code only. ### On Node 22.14.0 The packed CLI, installed by npm running on Node 22.14.0 (the official Windows build), as a customer on the CLI's lowest Node gets it: - **It installs**, with `EBADENGINE` warnings for `@scalar/json-magic@0.19.1`, `chokidar@6.0.0`, `undici@8.12.4` and `undici@8.12.3`. The first and the last are new with this PR: json-magic and the undici it pins. - **fumadocs-openapi 12.6.5 loads json-magic 0.19.1 there**, and its magic proxy follows a reference and a circular one. - **`portal generate` builds three portals:** the layout reproduction, the OAuth one, and a specification with nested, shared and circular `$ref`s across schemas, parameters, a request body and responses. - **The output is the same as this repository's install gives** (Node 24, json-magic 0.16.1). For two of those projects I compared every page's visible text and the data it is rendered from, the Markdown copies, the llms files and the search documents: 16 pages and 16 other files, none differ. - **`portal serve` works:** an operation page renders with its nested fields, the playground and the cURL sample, and saving the specification updates the page within two seconds. Not covered: Node 22.15 to 22.18 one by one, and macOS or Linux on 22.14 with json-magic 0.19. One thing this turned up that is not from this PR: an npm install resolves `zbsearch` 4.0.4 where the lockfile, on `dev` too, has 4.0.2, and the two write the search index differently inside. Its documents are the same. ## Pictures Five levels deep, 1142 px wide: the crumbs truncate and Unset is in reach.  A long inline code in a parameter's description, inside its card:  A long token in a security scheme's description, inside the popover:  ## Not in this PR - **Session replay markers on the playground dialog.** Fumadocs sets none yet, so the template still marks the dialog itself. ## After this merges - **#477 will conflict with it in two places.** That PR passes the listed scripts to `insertTags()` and edits `Analytics.loadTags()`, which this one removes. Whichever merges second resolves them: `insertTags()` keeps its new argument and the callback check, and `loadTags()` stays removed. - **apimatic/apimatic-io#2352 and the docs draft describe the old sign-in.** They say the tags wait on the page a sign-in returns to, and that a page opened with `?state=…` loads no tag. Both lines change with this PR. Part of apimatic/apimatic-io#2350 (points 3 to 6). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
dev took fumadocs-openapi 12.6.5 (#478), where a sign-in's answer reaches the playground through the tab's session storage and no page's address but the OAuth callback's holds it. insertTags() there holds the Google tags back on the callback only, and Analytics.loadTags() is gone. Listed scripts follow the same rule here: none on the callback, and all on the next page view. They used to wait wherever the address held an answer, which no page a reader returns to does any more. The test that held them back at such an address now holds them back on the callback, and a second one loads them at once on a page whose own link carries a state parameter. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed called a callback as a method of the record it keeps for that subscriber, so a callback written without strict mode got the record as `this`. Writing to it could reset the count delivery runs on, which handed the same event over without end, and a callback that expected the window there kept its state in the record instead. A callback is now called on its own, as any function is. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed sat at window.portalEventFeed, beside the mark of what the page started with. Both showed among the window's own names, and the feed there offered publish() to any script that came across it. The window now holds both under one key, a symbol, so it gains no name but apimatic and the data layer. A script that looks for the feed can still reach it, as it can anything on the page. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() took the head as its record of what it had inserted. A vendor's loader that removes its own element once it has run was inserted again on the next page view, so it ran twice on the first page and once more for every page after. The page now remembers each address it inserted, for a second instance under portal serve too, and no page view reads the head. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The start runs while the bundle loads, and it assigned to window.apimatic. Where a host had locked that name the assignment threw, the bundle stopped, and the page never came to life: no search, no theme switch, no listed script and no tag. The portal now starts all the same and shows the error in the console a moment later. Scripts on such a page get no subscribe(). Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The parser took https:///cdn.example.com/widget.js and wrote the address without the extra slash, while the schema marked it wrong in an editor. httpsAddress() now holds an address to the schema's pattern, for pluginUrl as for a script, and parses it once. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Script.staticFile() answered null for an address, which its caller had to filter out. It is staticFiles() now and answers a list, empty for an address. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A script that names no category counts as analytics, so the flag leaves it out, but the flag's help and the README named only the analytics and marketing scripts. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
deliveredCount and an Unsubscribe type replace the comments on the feed's count and on what subscribe() returns, and a two-line comment in the schema test is one line. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The description of portal.scripts still said they load once the address holds no OAuth answer. Since the merge with dev they load on every page but the OAuth callback. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A build made with --no-analytics left out the tags and the analytics and marketing scripts, and still handed every event, a reader's search terms among them, to the necessary and functional scripts it kept. The identity file now says whether the event feed is on, and it is off for such a build. subscribe() stays in place there and is handed nothing, so a kept script that calls it does not throw. The data layer gets its entries as before. The flag's help says what changed. AnalyticsConfig.withoutVendors() is withoutAnalytics() now that it turns off more than the vendors. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A consent tool listed in portal.scripts could lose a race with the
built-in Google tags: when it arrived after Google's library, cookies
were set and the page view was sent before it had said "denied".
portal.analytics.googleConsentMode, { "default": "denied" }, makes the
portal queue Google's consent defaults itself, before it sets either
tag up: the four Consent Mode v2 types denied, and a wait of 500 ms for
a consent tool to hand over a returning reader's answer. Both tags load
as before, and set no cookie until something on the page calls
gtag('consent', 'update'). A build made with --no-analytics queues
nothing.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers googleConsentMode, with default required and "denied" its one value. The schema test holds the schema and the parser to the same verdict on each case. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now sets googleConsentMode. A browser script has to hold the setting and the defaults it queues, and no prerendered page may hold them. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs_code_copy and docs_sdk_download each carried a key named language. gtag takes that name on an event for the reader's own language, so a code copy reached GA4 with its language field set to python, and the Language report listed code and SDK languages beside real ones. The key is code_language on a code copy and sdk_language on an SDK download, in the data layer, for a subscriber and in GA4 alike. A test keeps the name language out of every event. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs_search carried result beside result_count, and a reviewer read it as the list of results, sent empty. It is the address of the one result the reader picked, and empty when they picked none. The key is picked_result. Nothing else about the event changes. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An entry in portal.scripts that named no category counted as analytics, so --no-analytics dropped it. A customer who never chose a category had no way to see why a script was gone from a staging build. category is now required, by the parser and by the schema alike, and the CLI assumes none. --no-analytics still drops what it dropped: the analytics and marketing scripts. Its help and the README lose "or not set". oneOf() no longer takes a fallback, which only an optional setting needs: brand.colorMode gets its default through optional(), as before for the user. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…window "Page" meant two things in analytics.ts: a route the reader visits, as in docs_page_view, and one full load, whose state the window holds for every Analytics instance in it. PageAnalytics read as state kept per route. The second sense is the window's now: WindowAnalytics, held under WINDOW_ANALYTICS, with a comment saying it means the Window object, which a reload replaces. The comments in the feed and the vendor tags that spoke of the page's events and the page's gtag follow, and so do three test titles. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
start(), report() and reportPageView() each read the state the window holds. An instance whose start() asked for a reload, as a config save that adds a script makes one, had joined nothing, yet its reportPageView() found that state and inserted the new script into the window being left. start() now keeps the state it made or joined on the instance, and is the one place that reads the global. An instance that asked for a reload adds no tag and hands over no event. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The portal reused whatever window.gtag held. A browser answers that name with any element whose id is gtag, and a guide's heading gets its id from its text. On a fresh load of a built page with a heading called gtag, the portal called the heading, threw, and its whole script stopped: no search, no theme switch, no listed script. Every portal with Google Analytics had this, and with googleConsentMode every portal that sets it. Only a function counts now, where the tags are set up and where GA4 is sent an event. Seen on built files before and after; a preview does not show it, since its heading is not in the page when the script starts. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The build test looked for the text googleConsentMode and the text wait_for_update in a built script. Both are in every build: the first is a key of the identity file whatever its value, the second sits in a function that ships called or not. A build with the setting written as null passed. It now reads the setting's value, and a second build, which sets no consent mode, has to fail the same check. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…tics --no-analytics dropped googleConsentMode with the two Google tags, on the grounds that a staging build queues nothing for Google. It keeps necessary and functional scripts, though, and an owner may load a Google tag of their own from one of those. On staging only, that tag then started with no consent state: it set its cookies and sent hits while the banner was unanswered. The default stays in such a build. It does nothing where no Google tag loads. The tags, the analytics and marketing scripts and the events are left out as before. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The description said the setting starts "the Google tags set here" as denied. It applies with no Google tag set too, and it covers Google's own tags alone: a container can fire another vendor's tag, added as custom HTML, which follows Consent Mode only if it is given consent checks in the container. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Since the loader remembers what it inserted, where it once looked in the head, it no longer saw a script the host had put there itself. A host, or a snippet injector at its CDN, that adds the same consent banner or Google tag to every page got a second copy from the portal: two banners, and one still showing after the reader answered. The remembered addresses start with the src of every script the head holds when the portal starts, as written. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The portal put a new object at window.apimatic, built from the old one's own values and its analytics. A host that keeps an object of its own there, say an instance of a class, got back a copy with none of the class's methods, and its own reference no longer pointed at what the window held. analytics is now defined on the object that is there, when that object takes a property. A copy is made only for one that does not: a frozen one, or one that fixed the name. A page that made window.apimatic read-only therefore gets subscribe() too, unless it froze the object as well. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
https://\cdn.example.com/widget.js passed the schema and the CLI, and was written out as https://cdn.example.com/widget.js: an address parser reads a backslash as a slash and takes what follows it for the host. A slash in that place was already refused. A backslash is now refused anywhere before the path, by the schema's pattern and the CLI's alike, for scripts and for pluginUrl. One in the path is kept, as the parser gives it. The report names what is asked for: an address starting with 'https://' and a host. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
gtagFor() assigned window.gtag inside its return expression, which SonarCloud flags (typescript:S1121) on this pull request. The gtag is now set first and returned after. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…no-analytics report() pushed every event to window.dataLayer and quieted only subscribe(). A necessary or functional script the flag keeps can read the data layer, and so can a Tag Manager container such a script loads, which fires its tags on those events. The flag's help says it hands no event to the scripts that stay. a895b2c keeps the consent default for exactly that kind of script, so "no vendor reads them there", the reason the entries stayed, no longer held. report() now returns at once when the events are off. The consent default, queued in start(), is the one thing such a build leaves in the data layer. A preview made with the flag no longer shows in the console what would have been reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since b9450b7 a build made with --no-analytics reports no event to the data layer either, so the identity's switch turns off more than the feed scripts subscribe to. analytics.eventFeed in portal.identity.json is analytics.events. It is never a setting in apimatic.json, where the CLI still refuses it as unknown. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| }, | ||
| "scripts": { | ||
| "type": "array", | ||
| "description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, so list only vendors you trust.", |
There was a problem hiding this comment.
Tracked in apimatic/apimatic-io#2355: a listed script can read the token a reader gets from an OAuth 2.0 sign-in in the playground, which the playground keeps in session storage for the life of the tab.
For this PR, please name that token here, as the docs draft (apimatic/apimatic-docs#887) already does. Owners read this description in their editor, and today it covers only what readers type:
| "description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, so list only vendors you trust.", | |
| "description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, and the token an OAuth 2.0 sign-in leaves in the browser's session storage, so list only vendors you trust.", |
The issue's other item for you is a Fumadocs issue asking the playground not to keep that token in session storage for the rest of the tab.
A function or method whose doc comment, signature and closing brace have more characters than its body is an unnecessary abstraction. The rule replaces "a one-line call does not get a wrapper", which is one case of it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
| }, | ||
| "googleConsentMode": { | ||
| "type": "object", | ||
| "description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It holds back no script listed in 'scripts'.", |
There was a problem hiding this comment.
Suggest rewording the last sentence:
| "description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It holds back no script listed in 'scripts'.", | |
| "description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It does not affect which scripts in 'portal.scripts' are loaded, or when.", |
- "Holds back" is consent-tool jargon for delaying a script until the reader consents. The new sentence says the same in plain words: Consent Mode changes neither which listed scripts load nor when, while Google's own tags wait for the consent tool (up to
wait_for_update's 500 ms). 'scripts'sits underportal.analyticshere, so it can read as a sibling ofgoogleConsentMode. The full path matches the--no-analyticshelp text.
| "description": "What the script is for. --no-analytics leaves out the 'analytics' and 'marketing' scripts.", | ||
| "enum": ["necessary", "functional", "analytics", "marketing"] |
There was a problem hiding this comment.
Please define the four categories, and say why there are four
category is required on every script, and the Risk section lists its four names among what can't be taken back after a release. But nothing says what each one means:
- The schema says only "What the script is for. --no-analytics leaves out the 'analytics' and 'marketing' scripts."
- The docs page in apimatic/apimatic-docs#887 gives one example each (a consent banner, a chat or feedback widget, an analytics tool, an advertising pixel) and says "A category decides one thing: whether
--no-analyticsleaves the script out."
So today the four names make a two-way choice. necessary and functional behave the same, and so do analytics and marketing (Script.loadsWithoutAnalytics()), and the browser never sees the category.
Could you:
- Define each category in the schema description and on the docs page: what belongs in it and what doesn't. Please cover a few borderline scripts, such as a session recorder, an A/B testing tool, a status banner, or a feedback widget that also tracks.
- Explain why these four exist. The description says the later consent setting of apimatic/apimatic-io#2347 "holds scripts by category". If that's the reason, please say so, and say which consent-tool groups the four are meant to match.
- Say whether we may need more later, for example the
preferencesgroup some consent tools have. - Can we remove some? Adding a category later breaks no config, but removing or merging one breaks every config that uses it. With only one decision depending on the category today, starting with fewer names may be the safer choice, unless the consent setting needs all four.



PR 2 of apimatic/apimatic-io#2348:
portal.scriptsandwindow.apimatic.analytics.subscribe(). PR 1 and PR 3 merged as #473. The plan this was built from, step by step, is apimatic/apimatic-io#2351; where the code departs from apimatic/apimatic-io#2347, #2348 and #2349 it says where and why.Since the review of 2026-11-17 it also carries
portal.analytics.googleConsentMode, with which a consent tool can govern the built-in Google tags, and a--no-analyticsthat hands no event to the scripts it keeps.On 2026-11-18 it renamed three event keys that #473 had put out on the
betatag, and made a script'scategoryrequired. The same day it answered a re-review of the fixes, whose ten new findings are under "Before merging".Ready for review. What is still to do before it merges is under "Before merging": the docs draft, the portal tests on this branch, and the decisions to record in the issues.
What a customer can now write
srcis anhttpsaddress or a file undersrc/static/. A file is checked on disk like a logo.categoryisnecessary,functional,analyticsormarketing. It is required: the CLI assumes none.--no-analyticsonportal generateandportal serveleaves out theanalyticsandmarketingscripts along with the two Google tags. The scripts it keeps are handed no event:subscribe()is there and stays silent. The consent default ofgoogleConsentModestays in such a build.window.apimatic.analytics.subscribe(callback): every event so far, then each new one, as a frozen{ name, params, time, version: 1 }. It returns the function that stops delivery.googleConsentModemakes the portal queue Google's Consent Mode defaults ("denied", with a wait of 500 ms) before it sets either Google tag up. Both tags load as before and set no cookie until a consent tool callsgtag('consent', 'update', …). Without the setting nothing changes.docs_code_copycarriescode_languageanddocs_sdk_downloadcarriessdk_language, where 2.3.0-beta.1 sendslanguage.docs_searchcarriespicked_result, where it sendsresult.What is on the branch
One commit per step of the plan, then the fixes from two reviews, the merge with
dev, the two follow-ups to the second review, five changes of 2026-11-18, seven commits that answer the re-review of that day, and three that answer a review comment and SonarCloud after it.19cb032ascriptsentries with anhttpsaddress: parsed, written toportal.identity.json, inserted by the loader withasync = false. The key a start runs once by covers the list, so a config save underportal servereloads with the new one. An inserted tag is found by itssrcattribute, since a selector built from a customer's address misses on a backslash (replaced in78505ad0).2580c4easrc/static/assrc: checked on disk with the brand's files, written as its portal path, inserted under the base path.bf320b46category, and--no-analyticsdropping the two categories.PortalConfig.withoutVendors()becomeswithoutAnalytics(). The flag's help and the README say what it leaves out.7849475bEventFeedandwindow.apimatic.analytics, put in place at the start, before any tag or script is inserted, on every portal. What scripts are given there changed in5f220732.cea1bc0cscriptsinapimatic.schema.json, with onehttpsAddressdefinition thatpluginUrlnow shares.6782e26ca0c6d999window, which the whole-tree lint that runs after the tests refused, and CI failed on it.5f220732{ subscribe }atwindow.apimatic.analytics, bound and put in place whatever was there; the feed is held atwindow.portalEventFeed(moved inddbad82a). From the review of 2026-11-16 below.88fe45dc,8d117512insertTags()reads<head>once per call (not at all since78505ad0).6ed31b30publish()loops over the subscribers without copying them first, which SonarCloud flagged on this PR as needless. Two tests pin what the copy was guarding: a subscriber added, and one removed, while an event is being handed over.310f38abdev, which took fumadocs-openapi 12.6.5 in #478. A sign-in's answer now reaches the playground through the tab's session storage, anddevholds the Google tags back on the OAuth callback only. Listed scripts follow that rule: none on the callback, all on the next page. They used to wait wherever the address held an answer.d9058be4this, and one that reset the record's count was handed the same event without end. From the review of 2026-11-17 below, as are the seven commits after it.ddbad82awindow.portalEventFeedis gone, and so iswindow.portalAnalyticsStarted, which #473 set. A script that looks for the symbol can still reach the feed, as it can anything on the page.78505ad0insertTags()no longer reads<head>.97946a28window.apimaticread-only no longer stops the bundle. The portal starts, and the error shows in the console a moment later. Sincef7518097that error is left to a page that froze the object too.bc7ec368httpsAddress()refuses an address with no host before its path (https:///…), as the schema's pattern does, and parses it once.pluginUrlgoes through the same function.e50ac0acScript.staticFiles()answers a list, empty for an address, in place ofstaticFile()and itsnull.5f1d49d9367cf0betakes that out again: no entry is without one.07ee1f45deliveredCountand anUnsubscribetype replace two comments in the feed that restated the code, and a two-line comment in the schema test is one line.3df7c3ddscriptssays they stay off the OAuth callback page. It still described the hold that the merge withdevremoved.17ddf35f--no-analyticshands no event to the scripts it keeps.portal.identity.jsongainsanalytics.eventFeed, which is"off"for such a build (analytics.eventssince6792fa8d).subscribe()stays in place and silent, and the data layer gets its entries as before (it gets none sinceb9450b72).AnalyticsConfig.withoutVendors()becomeswithoutAnalytics(), and the flag's help says what it does. Finding 7 of the review of 2026-11-17.1547e424portal.analytics.googleConsentMode: the portal queues Google's consent defaults ahead of both vendors' setups, and a--no-analyticsbuild queues none (it queues them sincea895b2cd). Finding 2 of the same review.440f0b28apimatic.schema.json, with the schema test holding it to the parser's verdict.94c58970be9556c2languageondocs_code_copyanddocs_sdk_downloadbecomescode_languageandsdk_language. gtag takeslanguageon an event for the reader's own language, so GA4's language field readpythonfor a code copy. A test keeps the name out of every event. From a review of the docs PR.5ad3cfe8resultondocs_searchbecomespicked_result. Next toresult_counta reviewer read it as the list of results, sent empty.367cf0becategoryis required on every entry, by the parser and the schema. No entry counts asanalyticsany more. The flag's help and the README lose "or not set".oneOf()loses its fallback, andbrand.colorModegets its default throughoptional().95780b18WindowAnalytics, held underWINDOW_ANALYTICS, with a comment saying it means theWindowobject, which a reload replaces. "Page" in this code now means a route only. From a review comment on this PR, as is the next.37db2b44start()keeps that state on the instance and is the one place that reads the global. An instance whose start asked for a reload used to find the state anyway, and its next page view inserted the new script into the window being left. It now adds no tag and hands over no event.9a6e19b4window.gtagcounts as a gtag only when it is a function. A browser answers that name with an element whose id isgtag, such as a guide's heading, and on a fresh load of such a page the portal called the heading and its whole script stopped. Portals with Google Analytics had this from #473. New finding 1 of the re-review, as are the six commits after it by their numbers.7b491436a895b2cd--no-analyticsbuild keeps the consent default. A script such a build keeps may load a Google tag of its own. New finding 3.eb200e91googleConsentModesays "Google's own tags", says that other vendors' tags in a container need their own consent checks, and no longer says "set here". New finding 5.a3a04d3esrcof every script<head>holds when the portal starts, so a script the host injects itself gets no second copy. New finding 7, a regression of78505ad0.f7518097analyticsis defined on the object a host keeps atwindow.apimatic, when that object takes a property. A copy is made only for one that does not. New finding 6.ae99bcc137dcd1b3gtagFor()setswindow.gtagbefore it returns it, not inside the return expression, which SonarCloud flagged (S1121) after9a6e19b4.b9450b72--no-analyticsbuild writes no event towindow.dataLayereither:report()returns at once. The consent default, queued instart(), is the one thing such a build puts there. From a review comment on this PR.6792fa8danalytics.events, no longeranalytics.eventFeed, since it turns off the data layer's events too. It is still refused as a setting inapimatic.json.Decisions on record
Each is a departure from the issues, made with the reviewer during the build and written up in apimatic/apimatic-io#2351 (section 4 and section 1, row 22), except the four that answer the review of 2026-11-17 and the last two, of 2026-11-18, which are written up here only. The issues themselves are not edited yet.
attributes. An entry is{ src, category }. A file instatic/can add a vendor's tag and set its attributes, and Plausible, the issues' example, now gives out a site-specific address with an inline call. Adding the key later breaks no config.categoryis not written to the identity file. Nothing in the browser reads it in this release.src, not three. What is neither anhttpsaddress nor a file instatic/gets one report naming both choices.subscribe()returns, not inside it, soconst stop = subscribe(…)can callstop()on the first event.toJSON()does not writescripts, as it writes neitheranalyticsnorseo.--no-analyticsin the build test.portal-project-service.test.tsproves the identity file, as for feat(portal): load Google Tag Manager and GA4 from portal.analytics #473.leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics' or 'marketing', and hand no event to the scripts that stay."The Google Tag Manager and Google Analytics tags" became "the tags", and17ddf35fadded the events.5f1d49d9had added "or not set", which367cf0betook out with the default.--no-analyticsbuild hands no event to the scripts it keeps (17ddf35f). This reverses a bullet written here earlier on 2026-11-17, which called the open feed a design choice.subscribe()stays in place, so a kept script does not throw on a staging build.--no-analyticsbuild writes no event to the data layer either (b9450b72). This reverses what stood in the bullet above until 2026-11-18: "the data layer still gets its entries: no vendor reads them there". Sincea895b2cdkeeps the consent default for a Google tag a kept script loads, a vendor can read them there: a tag manager such a script loads fires on the data layer's events. The cost is that a preview made with the flag no longer shows in the console what would have been reported.necessaryscripts have run was considered and not built: it needs a queue for events, delays analytics by the slowest script, never starts if one hangs, and still races for a consent tool that sets its default late.googleConsentModeis Google's alone. It is{ "default": "denied" }, an object so that a later key changes no config, and it holds no listed script. The portal-wide consent setting of #2347, which holds scripts by category and giveswindow.apimatic.consent.update, stays a later phase under a key of its own.--no-analyticsbuild keeps the consent default (a895b2cd). This reverses what stood here until 2026-11-18, that such a build queues nothing for Google. It keepsnecessaryandfunctionalscripts, and an owner may load Google's own snippet from one of those, the route this description gives for no contact with Google before consent. On staging only, that snippet then started with no consent state. The default does nothing where no Google tag loads.categoryis required (367cf0be). This reverses the default ofanalyticsthat #2351 records. A reviewer's point: a customer who never chose a category has no way to see why--no-analyticsdropped a script. What the default guarded still holds, since only a script someone markednecessaryorfunctionalsurvives the flag. A missing category is reported as'portal.scripts[0].category' is required.No release hasscripts, so no config breaks.betatag (be9556c2,5ad3cfe8). A container built against 2.3.0-beta.1 that readsdocs.languageordocs.resultgets nothing from them after this, with no error. The docs were not published with that beta.Known limits
loadevent also does not fire in that time, so GTM's "Window Loaded" trigger waits with it. Underportal serveloadhad already fired. A script that fails outright (a host that does not resolve) holds nothing.--no-analytics.googleConsentMode, a listed consent script can still lose to the built-in Google tags. Measured with Google Analytics and the consent script 1.5 s late: Google set its_gacookies and sent the page view with no consent state. With the setting on, the same run set no cookie and marked the page view denied. A customer whose banner decides what is tracked has to set it, and the docs must say so.googleConsentModeis Google's advanced Consent Mode. Both tags load before the reader answers and send hits marked denied, with no cookie. A customer who wants no contact with Google before consent lists Google's own snippet from a file of theirs that waits; list order holds (measured).integrity. The key is refused as unknown, so a build fixes a script's address but not what it serves. A script listed by its address runs whatever the address serves at each page load: a change by its vendor, or by anyone who takes the address over, reaches a published portal without a rebuild. A file instatic/changes only with a rebuild, apart from code it loads from elsewhere. Documented rather than fixed, for now: a review comment on apimatic/apimatic-docs#887 asks the scripts warning to say so. An optionalintegritykey can come later without breaking a config.dev(fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478) the answer is in no page's address but the callback's, where nothing loads. It waits in session storage until a playground reads it, and on a page with no playground it stays for the life of the tab. A listed script that reads session storage can read it there: seen in a browser, a script starting on the returned page read the callback's address,codeincluded. fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is a decision still to make. Holding them until the playground has taken the answer would not keep a credential from them. Measured with a sign-in through the playground against a stub provider that answers in the implicit flow: a listed script starting on the returned page read the token in the waiting answer; the playground then kept the token in session storage, asfumadocs-openapi-auth-oauth, for the life of the tab; and the same script read it there at its next start, on a guide page with no playground.window.apimaticdoes not exist for a script the host injects into<head>itself, which runs before the portal's bundle. If such a script puts an object of its own atwindow.apimatic.analytics, the portal replaces it at its start, and callbacks queued on the old one are not carried over.window.apimaticread-only and froze its object gets nosubscribe(). The portal starts and works, and the error shows in the console. A listed script that callswindow.apimatic.analytics.subscribe()fails there. Where the object behind the read-only name still takes a property, the portal putsanalyticson it and nothing is in error (f7518097; seen in a browser for a read-only property, not run again for a getter alone).srcas written. The same file under another spelling of its address, relative where the portal writes it from the root, gets a second copy.https://:443/…,https://[::1/…andhttps://cdn.exa%mple.com/…. An editor shows no warning for them, andportal generatereports the address.Risk
Medium. #473 is out on the
betatag only, as 2.3.0-beta.1 (latestis 2.2.0, which has none of it). Nothing of this PR is released, and it builds on #473.What changes for every portal, scripts listed or not:
<head>once, at its start, for the scripts already there. This applies to the two Google tags too. It takeswindow.gtagas Google's only when it is a function: a browser answers that name with an element whose id isgtag, such as a guide's heading, anddev's GA4 tag calls whatever the name holds, which stops the portal's script on such a page.window.portalAnalyticsStarted, is held under a symbol on the window with the feed.window.apimatic.analytics, and keeps each reported event in memory for the life of the page.portal.identity.jsongainsanalytics.googleConsentModeandanalytics.events. A portal that sets no consent mode queues nothing new, and its events are on.pluginUrlis checked by the same rule from a shared function, and its pattern in the schema moved to a shared definition. ApluginUrlwith no host before its path (https:///…) or with a backslash in its host (https://host\x.zip) is now refused; the CLI used to accept both, writing the first without the extra slash and the second with a slash for the backslash.A portal with no
scriptsloads nothing new.What changes only for a portal that lists scripts: those scripts run on every page, the API playground included, with full access to the page. That is the feature, and choosing them is the customer's.
What cannot be taken back after a release: the shape of an entry, the four category names and that one is required,
window.apimatic.analytics.subscribe(), the event it hands over and the keys of each event, andgoogleConsentModewith its one value. Customers will write configs and scripts against them.What stands between this and a mistake:
6782e26c, whose five findings are fixed.6ed31b30, and a re-review at94c58970. Their fourteen and ten findings are answered under "Before merging".6ed31b30, which found no vulnerability.Where the cover is thin:
codeandstateand the starting page put in session storage, not with a provider's round trip. One sign-in was then run through the playground itself, against a stub provider that answered in the implicit flow. No real provider has been used.subscribe()forwarder (at6ed31b30), an open-source consent tool and an open-source session recorder. Not run: a commercial consent tool or replay tool, a chat widget, Segment, or a vendor that readsdata-attributes.--no-analytics. The re-review at94c58970read them; none has had a security review.portal generatefor the required category. The last two have a browser run on a preview. None has had a code or security review beyond the comment the last two answer, and neither end-to-end file was run locally for the last two.portal generatefor the address rule. None has had a code or security review. Two of them change what a host sees: whereanalyticsis put onwindow.apimatic, and which scripts in<head>count as inserted.--no-analyticsbuild behind them. None has had a code or security review beyond the comment and the SonarCloud issue they answer.googleConsentModeis open source and wired to Consent Mode by hand, as its guide shows. A commercial tool that queues its own default may behave as the stand-in did (see "Known limits").dev(310f38ab) changed when listed scripts load around a sign-in. That has unit tests, both end-to-end files, a browser run and the re-review at94c58970behind it, but no security review.No data or state to migrate. Nothing is stored, and
portal.identity.jsonis rewritten on every run.How to revert
dev, before a release: revert this PR's squash commit withgit revert. It is one commit, nothing depends on it yet, and there is nothing to migrate or clean up. The revert also takes--no-analyticsback to leaving out the two Google tags only, with its earlier help text and README lines, and takesscriptsandgoogleConsentModeout of the schema.googleConsentMode: a CLI without this change refuses both as unknown settings, soportal generateandportal servefail until the customer removes them.apimatic.json, rebuild and redeploy. Foranalyticsandmarketingscripts, building with--no-analyticsdoes the same.scriptsfromapimatic.jsonand rebuild. The portal then loads none, andwindow.apimatic.analyticsstays there unused.Before merging
devholds a--no-analyticsthat drops less than it will.6ed31b30, the last commit before the merge withdev: the whole suite and the lint, on Ubuntu, macOS and Windows with Node 22, 22.14, 24 and 26. On6782e26cthe tests passed (2,526 onubuntu-latest / Node 24) and the lint after them failed on the fixture script, whicha0c6d999fixes. The whole suite was not run locally.310f38ab, the merge withdev: all 16 checks.07ee1f45, after the second review's fixes: all 16 checks.94c58970: all 16 checks.367cf0be: all 16 checks.37db2b44: all 16 checks.ae99bcc1: all 16 checks.6792fa8d, the head: all 16 checks.94c58970(a second review, which read the fixes at that commit and raised ten new findings). Each was checked first: the dead page of finding 1 was reproduced on built files, and finding 4 on two builds. Fixed: a heading called "gtag" stopped the portal's script (1,9a6e19b4); a staging build dropped the consent default (3,a895b2cd); the consent setting's build test could not fail (4,7b491436); the schema promised more than Consent Mode does (5,eb200e91); a host's own object atwindow.apimaticwas swapped for a copy (6,f7518097); a script the host injects was loaded twice (7,a3a04d3e); a backslash passed for a host (8,ae99bcc1); a config save could insert the new script into the window being left (9,37db2b44, which a comment on this PR asked for). Not changed: listed scripts can read a sign-in's answer in session storage (2), which stays a decision to make, since holding them would not keep the token from them (see "Known limits"); and the list of wanted scripts is still built on each page view, and two field comments stay (10).5f220732and the two refactors after it:window.apimatic.analyticswas the feed object itself, sopublish()and the event list were reachable from any script;subscribethrew when called detached from that object; an object a page had already put at that name made every report throw;EventFeed.deliver()was a private instance method, which.ai/instructions.mdrules out; andinsertTags()read<head>once per script. Seen in a browser with a page's own stand-in set first. Left as they are, on purpose: an address with a space around it is refused while a static path with one is accepted; the event history is not capped; missing-file checks read a folder once per file. A security review of the diff found no vulnerability.6ed31b30, fourteen findings, each checked against the head, the runtime ones reproduced in a browser or in Node first). Fixed in the eight commits after the merge: a script that removes its own element was inserted again on every page view (1, and 10 with it); the feed was reachable atwindow.portalEventFeed(3); a page that had madewindow.apimaticread-only stopped the bundle (4); a callback got the feed's record of it asthis(5); the CLI accepted and rewrotehttps:///…, which the schema refuses (6, and the double parse of 11); the flag's help left out scripts with no category (9);staticFile()answerednull(12); three comments restated the code (14). Fixed after those, on the reviewer's word: a listed consent script could not hold back the built-in Google tags (2), bygoogleConsentModein1547e424; and--no-analyticshanded events to the scripts it kept (7), in17ddf35f. Left as they are, on purpose: the event history is not capped (8), as after the first review; the browser tells a portal file from an address by its leading/(13), which is the ruleapi-markdown.tsxondevuses for images, and tests pin what the CLI writes;isWebAddress(), which checks links and the site address, keeps its own rule (the rest of 11).analytics.ts: the name of the state a window shares (answered by95780b18and37db2b44, resolved), and--no-analyticswriting every event to the data layer (answered byb9450b72, resolved). SonarCloud's one new issue on this PR, S1121 invendor-tags.ts, is answered by37dcd1b3.a77f6aaf, have theportal.scriptspage withcategoryrequired, the CLI row with the flag's wording, a consent section forgoogleConsentMode, the sign-in section as it works since fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478, the three renamed event keys, and what the re-review's fixes change for a reader of them. That PR stays a draft until this is in a full release.devand not on a pull request: dispatch them on this branch.Test plan, automated
Run on the tree of
6782e26c; the lint and the analytics and feed tests again on6ed31b30, and the build test on8d117512. After the merge withdev, on310f38ab:tscfor all three,eslint ., everytest/portal-templatefile with the config, schema and flag tests (1,130 passing), and both end-to-end files (79 and 6 passing). After the second review's fixes, on the tree of07ee1f45:tscfor all three, everytest/portal-templateandtest/types/portalfile with the schema, flag,portal-source-context,portal-project-service,serveandquickstarttests (1,449 passing), and both end-to-end files (79 and 6 passing);eslint .on07ee1f45itself. After the two follow-ups, on the tree of94c58970:tscfor all three, those unit files withprepare-projectandportal-template.test.ts(1,491 passing), and both end-to-end files (80 and 6 passing);eslint .on94c58970itself.17ddf35fand1547e424each passed the type checks and those unit files on their own. After the three commits of 2026-11-18, on the tree of367cf0be:tscfor the CLI and the tests, the unit files those commits touch with the config, schema, source, project, serve and template ones (792 passing),test/e2e/portal-build.test.ts(80 passing) andeslint ..tscfor the template was run after the two renames, which are all that touch it. After37db2b44:tscfor the template and the tests, the analytics and feed tests (100 passing) andeslint .. After the seven commits that answer the re-review, onae99bcc1:tscfor all three, the config, schema, source, project, serve and template unit files (804 passing), both end-to-end files (81 and 6 passing) andeslint .. After the three commits that follow, on6792fa8d:tscfor all three, the same unit files (805 passing), both end-to-end files (81 and 6 passing) andeslint ..tscfor the CLI, the tests and the template (the template's known errors from ungenerated files only).eslinton each step's CLI and test files, andprettieron every changed TypeScript file. Neither reads the schema, andeslintskips the template'slib/.portal-config,portal-source-context,preview-config,portal-project-service,schema,analytics,event-feed,portal-template, and the action and command tests that read the default fixture. Each step added tests to its own files.eslint ., the whole tree, as CI runs it after the tests: clean on6ed31b30, on07ee1f45, on94c58970, on the tree of367cf0beand onae99bcc1.APIMATIC_E2E=1withtest/e2e/portal-build.test.ts: 81 passing onae99bcc1, 80 on94c58970and on the tree of367cf0be, 79 before the consent mode's test.APIMATIC_E2E=1withtest/e2e/portal-serve.test.ts: 6 passing, again onae99bcc1.Test plan, in a browser (run on Windows: headless Chrome, and one run in Firefox and in WebKit)
Against
portal serveand againstportal generateoutput served statically, with GTM and GA4 set. Listed addresses pointed at a localhttpshost, so order, delay, failure and silence were exact.<head>after the vendor tags,asyncfalse, and run in list order with the first served 1.5 s late. Seen on a preview and on a built portal. No prerendered page names one.\in its query included./js/…, and from/docs/js/…with a path inportal.site.url, on a preview and on a built portal.portal generatefails namingportal.scripts[1].src, and names the spelling on disk when only the case differs. A config save underservethat names one is refused and the page keeps what it had.367cf0be, when an entry could still have none). Six probes (one per category, one with none, one static file markednecessary). Without the flag all six run, on a preview and a built portal. With--no-analytics, on both: only thenecessaryandfunctionalones run, the host is never asked for the others, no Google tag is on the page, the page view is still reported. In the built files, none of 138 holds a dropped address or either ID.serve. Adding a script reloads the page with it. Editing the description reloads nothing. Under--no-analytics, adding ananalyticsscript changes nothing and adding anecessaryone reloads with it.name,params,time,version, both objects frozen. A subscriber that tried to change events changed nothing the next one saw. A one-time subscriber got one event and stopped. A throwing one showed one console error per event and stopped nothing. All of this on a preview; on a built portal under a path, the replay, a page change, the one-time subscriber and the throwing one.310f38ab). On/oauth/callback?code=…&state=…: no vendor tag, no listed script, no page view. Sent back from the callback to the page that started the sign-in: that page's address is its own, the tag and every listed script load at once, and the page view has the clean address. A listed script starting there could read the answer in session storage; on the API reference page it was gone once the playground had loaded, and on a guide page it stayed. The callback was opened by hand with a typedcodeandstate, and the starting page put in session storage, not a provider's round trip.stateof the customer's own (?state=CA, and?code=…&state=…in a page's own link; on310f38ab): the tag and every listed script load at once, and the page view is reported without them.MutationObserversaw the playground dialog already carrying every marker.07ee1f45). Before the fix it ran twice on the first page and once more on each page change. After it, once for the whole visit, across three page changes.window.apimatic(same preview), read-only and with a getter alone. Before the fix the bundle threw and the page never came to life: no theme switch, no listed script, no Google tag. After it the theme switch works, the Google tag and the listed scripts load, and the console shows the error. Run on the tree of07ee1f45; sincef7518097the read-only case getssubscribe()and shows no error (below).portal, andwindow.apimatic.analyticshassubscribealone, frozen. A callback written without strict mode that pushes tothis.vendorQueuefilledwindow.vendorQueue.94c58970; every hit was answered in the browser, so none reached Google). WithgoogleConsentModeand a consent stand-in 1.5 s late: the data layer leads with the portal's default, no cookie is set, and the page view is marked denied, on a preview and on built files. Without the setting the same run set_gacookies and sent the page view with no consent state.gtag('consent', 'update', …)the cookies appear and the next hit is marked granted. A returning reader whose answer came 300 ms after Google's library ran got a first page view marked granted.--no-analyticsand the event feed (preview and built files). A keptfunctionalscript that subscribes ran once and was handed nothing across three page views.subscribe()gave back a function, called detached too; the data layer held each page view; there was nowindow.gtagand no Google tag. Without the flag the same script got all three. Run beforea895b2cd: with the consent setting, such a build now queues the default and has awindow.gtag. Sinceb9450b72the data layer holds no page view either (below).--no-analyticsand the data layer (built files on6792fa8d,googleConsentModeset, anecessaryscript standing in for a tag manager that watches the data layer, and Google's own snippet listed asfunctional). After a fresh load, a page change and a search, the data layer holds the consent default, the snippet's own commands and Google'sgtm.domandgtm.load, and nodocs_event. The stand-in saw no portal event, a subscriber got none, no cookie was set, and the snippet's page view was marked denied.94c58970). With neither host inscript-src, the listed address and Google's tag are refused, the listed file after them still runs and gets its events, and the theme switch and the in-app links work. With both hosts added, everything loads.portal.scriptsbeside GA4 built in withgoogleConsentMode, and wired to Consent Mode as its guide shows; a preview at94c58970). On a first visit the banner is up, the portal's default leads the data layer, no cookie is set and the page view is marked denied. After "Accept all" the tool sends its update, the_gacookies appear and the next hit is marked granted. On a return visit with the answer stored there is no banner, the update lands ahead of the first page view, and that page view is marked granted. Tag Assistant was not used: the hits themselves were read.portal.scripts; the same preview). With the playground open, a number typed into its field is not in the recording, which holds a blocked placeholder for the dialog. A term typed into the search box is in it. This proves therr-blockmarker alone; the markers for Hotjar, Clarity, FullStory, LogRocket, PostHog and Amplitude were not tried against those tools.94c58970). In both: the listed scripts sit in<head>in list order and not async; with the first served 1.5 s late, the files after it still ran after it; each ran once across four page views, one that removes its own tag included; a forwarder got every page view, and a late subscriber was handed all four;subscribealone, frozen; the theme switch and in-app links work, with no error.code_language,sdk_languageandpicked_result. GA4's language field staysen-uson each. Before the rename a code copy set it to the code's language.9a6e19b4, on a fresh load of a guide with that heading:window.gtagis the heading, the console showsa(...) is not a function, search does not open, the theme switch does nothing, no listed script runs and no hit is sent. After it all of those work and the consent default leads the data layer.--no-analyticsonae99bcc1, the snippet listed asfunctional,googleConsentModeset and no built-in tag). The data layer leads with the consent default, no cookie is set, the snippet's page view is marked denied, and a subscriber is handed nothing.ae99bcc1, the tag for a listed file added to one page's<head>by hand). It runs once and<head>holds one tag for it, on the fresh load and after two page changes.window.apimatic(same files, the object set before the portal's script). After the start it is the same object, its class's method works, andsubscribeis there. A read-onlywindow.apimaticholding an ordinary object getssubscribetoo, with no error.portal generateonae99bcc1). Refused for a listed script and forpluginUrl, with the report that asks for a host; so ishttps:///…. A backslash in the path is accepted.37db2b44(preview, on its tree). Saving a description reloads nothing and runs no script again, and the subscriber gets the next page view. Adding a script reloads the page with it, and a counter kept across the reload shows the added script ran once.portal generate, on the tree of367cf0be). It stops and reports'portal.scripts[0].category' is required.for the entry that names none, and the four choices for one that is misspelt.🤖 Generated with Claude Code